Week Of: 2022-11-06
2022-11-06

About Mattermost #

Mattermost offers a purpose-built collaboration platform designed for development workflows. The platform helps my team plan, organize, and run software development projects, while seamlessly integrating with communication and collaboration tools.more aboud Mattermost

Disclaimer & assumptions #

• There is endless best practices on managing servers security in general and specifically AWS services. here I have focused on the easiest configuration with the lowest risk as I see it.
• The guide is writen with an assumption that:
  • You already have AWS active account.
  • The guide has writen using the AWS' region staying in Frankfurt (Which is the closest site to Israel) so this may differ from AWS-region to another (like the location of the buttons on the screen and etc.)
  • You own a domain name.
• Parts of this guide (Mainly in the parts concerning the host configuration) is based on the official Mattermost's guide

AWS Intance configuration #

1. In your AWS account go to the EC2 console
2. Click on Instances
3. Launch instances button
4. Fill up the Instance Name
5. Don't need to change the defaults (Free tier eligible) in the sections:
   • Application and OS Images
   • Instance type
6. In the section Key pair, click on "Create new key pair"
7. In the "Create key pair" window, give the SSH name(e.g. "myssh").
   The default attribute should remain as is - Key pair type=RSA Private key file format=.pem
8. Click on Create key pair
9. The .pem file will be automatically downloaded.
10. In the Network settingsCheck section, check the box Allow HTTPS traffic from the internet
11. (recommanded if you've a static IP address) In the Network settingsCheck open the list next to Allow SSH traffic from and chose the value My IP
12. Finally, click on Launch instance button located at the bottom of the page.
    You'll get a Success massege with a link to your new instance. click on the link.

Allocation of static IP #

1. On the left menu, of the EC2 console that opened, under the section Network & Security, click on the menu Elastic IPs
2. Allocate Elastic IP adress
3. Click on Allocate button located at the bottom of the page.
   You'll be returned to the Elastic IP addresses  and will see your new IP adress.
4. check this line, and open the Action menu
5. Associate Elastic IP adress
6. In the opened window, Click on the Instances field, and from the list choose your instnace.
7. In the Private IP Adress choose one of your available IPs.
8. Click Associate

SSH connect to the instance #

1. Open CMD / Terminal and navigate to the folder containing the .pem file, that has been downloaded (using CD)
2. Type the following command:

ssh -i <pem file name> <public IP / DNS>

For example:

ssh -i ec2.pem ec2-user@18.205.46.80

3. You will then be asked "Are you sure... (yes/no)", Obviously type the answer - yes
   You will be connected to your instance.

Install Docker & Docker-compose #

Docker #

sudo yum install docker

Approve the installation.

Start the Docker service:

sudo systemctl start docker

Verify that the installation was successful by viewing version information:

docker version

Docker-compose #

sudo curl -L "https://github.com/docker/compose/releases/download/1.28.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

Set permissions so that the docker-compose command is executable:

sudo chmod +x /usr/local/bin/docker-compose

Now, the docker-compose is staying in the /usr/local/bin which is not on the PATH. To fix it, create a symbolic link:

sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

Verify that the installation was successful by viewing version information:

docker-compose --version

Git #

sudo yum install git

Verify that the installation was successful by viewing version information:

git version

Deploy Mattermost on Docker #

1. In a opened terminal window, clone the repository and enter the directory.

git clone https://github.com/mattermost/docker
cd docker

2. Create your .env file by copying and adjusting the env.example file.

cp env.example .env

3. Before the next step, if you own domain name, add a record to your DNS:

Type: A 
Name: <sub.domain.name>
Value: <Your public IP address>
TTL: 3600

You have to verify the completion of this process before you'll move to the next step.
you can check it easily with DNS Checker tool
4. Edit the DOMAIN value in the .env file to correspond to the domain for your Mattermost server.
Edit the .env file:

nano .env

When you'll finish, type Ctrl+s then Ctrl+x to exit the editor.

5. Create the required directories and set their permissions.

mkdir -p ./volumes/app/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes}

sudo chown -R 2000:2000 ./volumes/app/mattermost

TLS Configuration #

Configure TLS for NGINX (optional). If you’re not using the included NGINX reverse proxy, you can skip this step.

If you need to create a new certificate and key:

bash scripts/issue-certificate.sh -d <YOUR_MM_DOMAIN> -o ${PWD}/certs

To include the certificate and key, uncomment the following lines in your .env file and ensure they point to the appropriate files.

• CERT_PATH=./certs/etc/letsencrypt/live/${DOMAIN}/fullchain.pem
• KEY_PATH=./certs/etc/letsencrypt/live/${DOMAIN}/privkey.pem

If you're using a pre-existing certificate and key:

mkdir -p ./volumes/web/cert

cp <PATH-TO-PRE-EXISTING-CERT>.pem ./volumes/web/cert/cert.pem
cp <PATH-TO-PRE-EXISTING-KEY>.pem ./volumes/web/cert/key-no-password.pem

Verify keys path #

To include the certificate and key, ensure the following variables in your .env file points to the appropriate files.

CERT_PATH=./volumes/web/cert/cert.pem
KEY_PATH=./volumes/web/cert/key-no-password.pem

Deploy Mattermost. #

Without using the included NGINX:

sudo docker-compose -f docker-compose.yml -f docker-compose.without-nginx.yml up -d

To access your new Mattermost deployment, navigate to http://<YOUR_MM_DOMAIN>:8065/ in your browser.

To shut down your deployment:

sudo docker-compose -f docker-compose.yml -f docker-compose.without-nginx.yml down

Using the included NGINX:

sudo docker-compose -f docker-compose.yml -f docker-compose.nginx.yml up -d

To access your new Mattermost deployment via HTTPS, navigate to https://<YOUR_MM_DOMAIN>/ in your browser.

To shut down your deployment:

sudo docker-compose -f docker-compose.yml -f docker-compose.nginx.yml down

Finally #

Congrulations! you've finfshed configuring your Mattermost system.
Now you can create your first Mattermost System Admin user, invite more users, and explore the Mattermost platform.

Maintenance #

Renew SSL Certificate #

Refer to the guide here: Renew SSL certificate of the mattermost

Upgrade from mattermost-docker #

For an in-depth guide to upgrading from the deprecated mattermost-docker repository, please refer to this document. For additional help pr questions, please refer to this issue.

Installing a different version of Mattermost #

1. Shut down your deployment.

2. Run git pull to fetch any recent changes to the repository, paying attention to any potential env.example changes.

3. Adjust the MATTERMOST_IMAGE_TAG in the .env file to point your desired [enterprise](https://docs.mattermost.com/install/(https://hub.docker.com/r/mattermost/mattermost-enterprise-edition/tags?page=1&ordering=last_updated) or team image version.

4. Redeploy Mattermost.